/*
 * BufferPool.java    0.0.1    17/set/2009
 * 
 * Copyright (c) 2009 mentalsmash.org
 * 
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 *
 * The use of the Apache License does not indicate that this project is
 * affiliated with the Apache Software Foundation.
 */ 
package org.mentalsmash.tazio.net.cs.server.impl;

import java.nio.ByteBuffer;
import java.util.NoSuchElementException;

import org.apache.commons.pool.ObjectPool;

/**
 * This interface extends the org.apache.commons.pool.ObjectPool interface.
 * It is intended to serve as a pool of ByteBuffers, since they are a precious resource.
 * @version    ver    17/set/2009    
 * @author     Andrea Reale <andrea.reale@gmail.com>
 *
 */
public interface BufferPool extends ObjectPool {

	/**
	 * {@inheritDoc}
	 */
	ByteBuffer borrowObject() 
		throws Exception, NoSuchElementException, IllegalStateException;
	
//	/**
//	 * Obtains a ByteBuffer instance from this pool, asking for the specified capacity.
//	 * <p>
//	 * No guarantee is given that the returned buffer will have the desired capacity, so check it out
//	 * with {@link java.nio.ByteBuffer#capacity buffer.capacity()}. Also notice that the maximum capacity for a buffer also
//	 * depends on the settings of the Factory used to allocate buffers.
//	 * (see {@link org.mentalsmash.tazio.net.server.ByteBufferFactory ByteBufferFactory})
//	 * </p>
//	 * <p>
//     * Instances returned from this method will have been either newly created with
//     * {@link PoolableObjectFactory#makeObject makeObject} or will be a previously idle object and
//     * have been activated with {@link PoolableObjectFactory#activateObject activateObject} and
//     * then validated with {@link PoolableObjectFactory#validateObject validateObject}.
//     * </p>
//     * <p>
//     * By contract, clients <strong>must</strong> return the borrowed instance using
//     * {@link #returnObject returnObject}, {@link #invalidateObject invalidateObject}, or a related method
//     * as defined in an implementation or sub-interface.
//     * </p>
//     * <p>
//     * The behaviour of this method when the pool has been exhausted
//     * is not strictly specified (although it may be specified by implementations).
//     * Older versions of this method would return <code>null</code> to indicate exhaustion,
//     * newer versions are encouraged to throw a {@link NoSuchElementException}.
//     * </p>
//     *
//	 * @param capacity
//	 * @return an instance from this pool
//     * @throws IllegalStateException after {@link #close close} has been called on this pool.
//     * @throws Exception when {@link PoolableObjectFactory#makeObject makeObject} throws an exception.
//     * @throws NoSuchElementException when the pool is exhausted and cannot or will not return another instance.
//	 */
//	ByteBuffer borrowObject(int capacity)
//		throws Exception, NoSuchElementException, IllegalStateException;
	
	 /**
     * Return an instance to the pool.
     * <p>
     * By contract, <code>obj</code> <strong>must</strong> have been obtained
     * using {@link #borrowObject() borrowObject}
     * or a related method as defined in an implementation
     * or sub-interface.
     * </p>
     *
     * @param obj a {@link #borrowObject borrowed} instance to be returned.
     * @throws Exception 
     */
	void returnObject(ByteBuffer obj) throws Exception;
	

}
